Teach Yourself VRML 2 in 21 Days

home *** CD-ROM | disk | FTP | other *** search

/ Teach Yourself VRML 2 in 21 Days / Teach Yourself VRML 2 in 21 Days.iso / mac / ISO9660 / 3rdparty / POLYTRAN / dos / PT_DOS.ZIP / DOC_1 / PT.1 < prev next >

Wrap

Text File | 1996-06-13 | 21.6 KB | 460 lines

.so psroff.inc # Include the macros needed for output to Postscript .TH Introduction .SH NAME PolyTrans \- A command line interface to the PolyTrans Geometry Conversion Filters .SH COMMAND SYNTAX .PP .nf pt [import options] [export options] [@filename] list_of_input_files .fi .PP [import options] optionally contains one of the following commands, in addition to zero or more options specific to the selected import converter (which are themselves described in separate man pages): .TP -i 3ds = Import a 3D Studio scene, project or material file .TP (.3ds, .prj, .mli). .PD 0 .TP -i alias = Import Alias triangle file (.tri) .TP -i cad3d = Import a CAD 3D binary scene file (.3d2) .TP -i dem = Import a USGS DEM (Digital Elevation Model) file (.dem) .TP -i dxf = Import a binary or ASCII DXF file (.dxf) .TP -i iges = Import an IGES ASCII object file (.igs, .iges) .TP -i ima = Import an Imagine scene file (.iob, .obj) .TP -i lsa = Import a Lightscape ASCII object file (.lsa) .TP -i lw = Import a Lightwave object file (.lw, .lw*, .lwb) .TP or Lightwave scene files (.lws*, .scn, .scene, scene*) .TP -i nff = Import Haines NFF file (.nff) .TP -i ng_bdf = Import a NuGraf binary scene file (.bdf) .TP -i ng_scr = Import a NuGraf ASCII script file (.scr) .TP -i slp = Import Pro/Engineer Render file (.slp) .TP -i stl = Import StereoLithography file (.stl) .TP -i true = Import Caligari trueSpace files (.cob, .scn) .TP -i vpro = Import a Vistapro DEM (Digital Elevation Model) file (.dem) .TP -i wave = Import a Wavefront ASCII object file (.obj) .PD .PP NOTE: This -i command is optional. If not specified then the converter will try to guess a file's format by matching the input filename's file extension to one of the file types listed above (ie: .3ds = 3D Studio). The converter will then examine the file to see if it is the correct format; if the converter cannot determine the file format type then you must specify the -i command explicitly. .PP [export options] must contain one of the following mandatory commands, in addition to zero or more options specific to the selected export converter (which are themselves described in separate man pages): .TP -o 3ds = Export to a 3D Studio binary file (.3ds) .PD 0 .TP -o dxf = Export to a DXF ASCII file (.dxf) .TP -o ng_bdf = Export to a NuGraf binary scene file (.bdf) .TP -o rib = Export to a RIB ASCII file (.rib) .TP -o opengl = Export to an Open GL C Code file (.c) .TP -o povray = Export to a POV-Ray v2.0 ASCII file (.pov) .TP -o wave = Export to a Wavefront ASCII file (.obj) .TP -o vrml = Export to a VRML ASCII file (.vrml, .wrl) .PD .PP and 'list_of_scene_files' is one or more input files each of which must have the same file extension as listed in the '[import options]' above (ie: a 3D Studio file name must end in the '.3ds' extension). .PP .SH OPTIONAL INPUT BATCH FILE .PP An alternative method of specifying the command line arguments is to place some or all of the arguments within an ASCII text file and have the converter read the arguments from the command file instead of the command line. The text filename is specified by preceeding it with the '@' character on the command line. .PP For example, if the following parameters are placed in the text file 'my_cmds', .PP .nf # --------------------------------- # Argument command file -o wave -in-lw-compute-normals = on -in-lw-print-stats = on -in-lw-smoothing-angle = 60.0 house.lw doors.lw # --------------------------------- .fi .PP then these arguments can be read into the converter as 'pt @my_cmds'. .PP NOTES: .IP Any object filenames must be specified LAST in the text file after all other command line options. .IP The text file CANNOT accept wildcard specifications for the filenames, unlike the command line. For example, on the command line you can use the '*.3ds' to specify the input filenames but within the text file you must explictly specify each filename without the wildcard '*' character. .PP .SH EXAMPLE COMMAND SYNTAX .PP The following section illustrates various ways to execute the PolyTrans program. .PP The following example reads in the 3D Studio file called 'testfile.3ds' and exports it to a DXF file with the same base filename: .IP pt -i 3ds -o dxf testfile.3ds .PP The following example is the same as the previous example except that no input format command is given. The converter will try to guess at the input file's format by looking at its extension (.3ds) then it will examine the file itself to make sure it is the correct format: .IP pt -o dxf testfile.3ds .PP This example will read in some of the arguments from the ASCII text file 'my_args' (as shown above) and specify some additional input objects: .IP pt @my_args window.lw lights.lw .PP This example shows how explicit import and export directories can be specified. All files will be read from the '-id' directory and saved out to the '-od' directory: .IP pt -id = "c:\input" -od = "c:\output" -o vrml bike.lw .PP This example batch converts a variety of input formats to a single 3D Studio output file: .IP pt -of = output.3ds -o 3ds bike.lw table.obj desk.dxf .PP Again, this batch converts all Wavefront files located in the input directory to separate DXF output files: .IP pt -i wave -o dxf *.obj .PP .SH COMMON COMMAND LINE OPTIONS .PP The following options are common to all import/export converters. All other options are listed in separate man pages: .TP -of = "output filename" This option specifies an explicit filename that all imported file(s) are to be saved out to. For example, if the command is specified as "-of = mydata -o 3ds file1.obj file2.igs" then the two input files will be saved out to the filename "mydata.3ds". Note that no file extension (such as ".3ds") is required because the program will automatically append it for you. If this '-of' option is not specified then each imported file will be exported to a unique file with the same root filename as the input filename but with the file extension changed (ie: input.3ds -> input.obj). .TP -id = "directory path" This option allows a directory path to be specified where all input file(s) will be read from. For example, "-id = c:\input" will cause all files to be read in from the top-most "input" directory located on disk drive C. UNIX or DOS-based pathnames are valid. If a file is not found then it will be searched for in the list of directories contained in the environment variables 'NG_SEARCHPATH_OBJECTS' and 'NG_SEARCHPATH_DEFAULT' (see explanation below). .TP -od = "directory path" This option allows a directory path to be specified where all exported file(s) will be stored. For example, "-od = c:\exported" will cause all exported files to be placed in the top-most "exported" directory located on disk drive C. UNIX or DOS-based pathnames are valid. .TP -backupfiles = [ on | off ] This option allows the program to create a backup file if a file is about to be overwritten with a new version. For example, if the program is about to output a new file called "file.3ds" which already exists on disk then the program will first rename the current version to "file.bak" before writing the new version. If backup copies of the file already exist from previous executions of the translator program then the backup file extension will use sequential numbers (for example, "file.bk1", "file.bk2"). Thus, successive backups will use the file extensions: .bak, .bk2,. bk3, etc. .TP -confirmoverwrites = [ on | off ] Enable or disable the confirmation of file overwrites. If set to 'off' then files are always overwritten without user confirmation. If set to 'on' (the default) then potential file overwrites are always confirmed by the user. This option is ignored if the '-backupfiles' option is set to 'on' in which case backup files will always be created. .TP -quiet = [ on | off ] Enable or disable all printing to the console window. It is 'off' by default, allowing all messages to be displayed to the console window. .PP .SH POLYGON PROCESSING FUNCTIONS .PP The following command line options provide access to functions that operate on raw polygon data, such as removing redundant vertices, unifying the direction of normals and adding vertex normals (used to create a 'smooth' appearance for the data). Note that these functions are only applicable to objects which contain polygon data (they are not used on objects which contain NURBs, bicubic patches or solid objects). These polygon processing functions, if enabled, are applied to the polygon data after it has been imported into the internal database but before it has been exported. .PP Note that in most cases you will not have to use these functions since most of the import converters process their input data automatically (such as in the DXF and IGES readers) using these same polygon processing functions. Nevertheless, you can enable these functions if you want to fine tune the data before it is exported. .PP Six functions are available and are performed in the order as specified as follows: .TP -weldvertices = <threshold distance> This function will delete all redundant vertices which are within a specified distance of each other. The distance value is specified with the floating point <threshold distance> parameter. To enable this function use a value >= 0.0 (a value of 0.001 is appropriate for some datasets). Note that the threshold value is dependent upon the size of your dataset; basically you will have to make an educated guess at a good <threshold distance> value. Please note that this function can become VERY SLOW for data sets with thousands of polygons in it (every vertex must be compared against every other vertex). To disable this function set the <threshold distance> parameter to -1 or else do not specify this option on the command line. .TP -unifynormals = [ yes | no ] For some 3d models, in particular those created using Autodesk's AutoCAD, there is no consistent orientation of the polygons; ie: some polygons of a surface are oriented clockwise (the geometric normal points inward) while the remaining polygons are oriented counterclockwise (the geometric normal points outward). This is a problem for the '-autosmooth' option shown below since all of the polygons must have the same orientation in order for the smoothed vertex normals to be computed properly. .IP If this option is enabled (set to 'yes') then a special algorithm will be used to walk over the polygon mesh and reorient each polygon. Note, however, that adjacent polygons MUST share the same vertices for this algorithm to work; you can ensure that the vertices are shared by enabling the '-weldvertices' option above. .TP -flipnormals = [ outward | inward | disabled ] If this option is set to 'inward', and the program determines that most of the geometric normals of the polygon data point outwards, then this routine will reverse the orientation of all polygons and flip their vertex normals so that the majority of geometric normals point inward towards the centroid of the polygon data. .IP If this option is set to 'outward', and the program determines that most of the geometric normals of the polygon data point inwards, then this routine will reverse the orientation of all polygons and flip their vertex normals so that the majority of geometric normals point outward away from the centroid of the polygon data. .IP To disable the '-flipnormals' function use the 'disabled' option, or don't specify this option on the command line. .TP -autosmooth = <angle in degrees> This is a very useful function which automatically creates vertex normals for polygonal data that does not have any. Vertex normals are an integral part of the rendering process which basically describe the 'smoothness' or 'curvature' of an object. For example, even though a sphere is made up of flat polygons it appears smooth after rendering because of the precise vertex normals assigned to it. .IP Many objects that you will read into this translator program will not contain vertex normals, or the vertex normals they do contain may not be to your liking. In this case you can use this function to compute new vertex normals for the data. The vertex normals are computed based on the angle between abutting polygons; if the angle between the geometric surface normals of abutting polygons is less than the <angle in degrees> parameter then common vertex normals will be assigned to the polygons (they will be smoothed); thus, higher values make the object appear to be smoother and have less sharp corners. The range for the <angle in degrees> parameter is 1 to 180 degrees (this function can be disabled by setting this parameter to 0). .IP This function can be applied to the data as many times as you like (you can keep increasing the smoothing angle argument until the geometry looks good). .IP NOTE that smoothed normals can only be created if abutting polygons share the same vertices. This will be the case for most data, but for some data (such as polygons read in via the IGES converter) each polygon will have its own unique vertex copies. In this case you have to apply the '-weldvertices' function described above before you smooth out the data. .IP ALSO NOTE that the geometric normals of the polygons must be oriented consistently; ie: the normals belonging to neighbouring polygons must be on the same side of all polygons. If this is not the case then enable the Make polygon orientations consistent option above. .IP In closing, if the '-autosmooth' function reports '0 normals computed' then: .IP Apply the '-weldvertices' function to the data and try again. .IP Or, this object does not have any raw polygons in it so ignore the problem. .TP -weldothers = <threshold distance> This is the same as the '-weldvertices' function except that it combines redundant normals, texture coordinates, colors, U tangent vectors and V tangent vectors of the polygon data that are within a certain threshold of each other. In most cases this function is not required. An appropriate value for <threshold distance> is 0.001. To disable this function set the <threshold distance> parameter to -1 or don't specify it on the command line. .TP -flipallnormals = [ yes | no ] If this option is enabled then the orientation of all vertex normals will be flipped. For example, if the vertex normals of the object currently all face inward then this function will cause all of the vertex normals to face outward. .TP -removedblsided = <threshold distance> Some modeling and rendering programs create what are called "double sided polygons" which are actually two identical polygons that share the same location in space except that they have opposite orientations (the geometric face normals point in opposite directions). These double sided polygons can cause major problems with other rendering programs which cannot handle double sided polygons - in this case the '-removedblsided' option can be enabled which will remove all such duplicated polygons. Two polygons are considered to be "double sided" if each corresponding vertex is within a maximum distance of each other - this maximum distance is set with the <threshold distance> parameter. If this parameter is set to 0 then both polygons must be situated in exactly the same location in space, else the parameter can be increased to provide for leeway between vertex locations (a value between 0.000001 and 0.001 should be fine). .PP .SH OVERVIEW OF THE POLYTRANS PROGRAM .PP PolyTrans is a command line interface to the suite of PolyTrans Geometry Conversion Filters that convert between various 3D geometry file formats. This program is based upon the same code used in the NuGraf Rendering System, which is a high-end, interactive rendering and visualization program. Since this program is based on a highly complex rendering system it can import, convert and export many more entities and attributes than most other polygon format converters, and with much more flexibility. .PP Whereas other converters will only read in straight polygon data, PolyTrans will read in many higher-order entities such as NURB and Bicubic patches, a variety of indexed and meshed polygon formats, and a variety of quadric primitives such as spheres and cones. In addition, PolyTrans will also read in all material attributes, cameras, lights and other scene data associated with the input file (where appropriate). .PP The real power of the PolyTrans program lies in its output converters. As part of the conversion process PolyTrans can accommodate any type of output format, from the simplistic DXF format to complex formats such as RIB and 3D Studio. In terms of the simplistic output formats (such as DXF), the converters will convert all input entities to polygons. For example, if an input file contains NURB patches and spheres, then the converter will tessellate these higher-order entities directly into polygons. On the other hand, if the output format can accommodate higher-order entities, such as the RIB format, then the converter will output the entities in their original input form (NURB or Bicubic patches, spheres, or just meshed polygons). Thus, input entities are not broken down into polygons unless absolutely required by the output format. .PP A technically advanced feature of the conversion process is the use of a unique memory allocation and memory management system. This system, which is used by the various import and export filters, as well as the internal database manager, allows huge databases to be converted on machines with minimal memory. Rather than allocate numerous small chunks of memory, the manager allocates large blocks of memory whose size is determined by the converter; the DXF and Wavefront import filters, for example, greatly benefit from this memory manager since hundreds of thousands of small memory elements must be allocated during the import process. In addition, the import converters store all polygon data within the database using a compressed mesh format which uses various techniques to reduce memory usage (such as sharing the normal/texture/color/etc index arrays with those of the vertex index array). All this adds up to an efficient use of memory resources. .PP A wide selection of other output options allow the converters to automatically triangulate the output data, cut holes out of meshes (when necessary) and tear apart the input data according to material assignment or grouping (refer to the RIB and Wavefront export modules). In addition, the converters always output optimized polygon meshes wherever possible, regardless of the form or structure of the input polygon data (arbitrary polygon input data is always welded, optimized and any redundant polygon coordinates removed before being output). In general the converters can convert any form of input to any form of output. .PP Another important feature of the converters is that they convert _all_ attributes associated with a polygon mesh, such as the vertex normals, vertex colors, u/v texture coordinates and U/V tangent vectors. The texture coordinates are particularly important when converting polygon data. .PP .SH SETUP FILE .PP When the PolyTrans program initializes it looks for a setup file which contains all of the default settings for the various import/export converters. This setup file is loaded in after the program has initialized but before any command line arguments are processed or any object files loaded (thus the command line arguments override the options specified in the setup file). .PP The name of the setup file is different for each different operating system and machine type: .nf setup.sgi - Silicon Graphics setup.sun - SUN Microsystems setup.dos - MSDOS or Windows 95/NT command line version setup.lnx - Linux setup.ini - If none of the above are found .fi .PP .SH INPUT FILENAME SEARCH PATHS .PP When opening the input object files the converter will search several other directories if it does not find a file in the current directory. These alternative search paths are listed at the end of the 'setup.ini' file. .PP The default search paths are defined as such: .PP .nf NG_SEARCHPATH_DEFAULT = "$(NG_WORKING_DIR);$(NG_WORKING_DIR)/objects" NG_SEARCHPATH_OBJECTS = "$(NG_WORKING_DIR);$(NG_WORKING_DIR)/objects" .fi .PP The input file will first be searched for in the directories listed in the NG_SEARCHPATH_OBJECTS environment variable then in the directories listed in the NG_SEARCHPATH_DEFAULT environment variable. Each directory is separated by a comma in each environment variable. .PP Upon startup of the converter, the $(NG_WORKING_DIR) argument shown above will be replaced with the directory name where the converter program was first executed. .PP In addition, you can specify an explicit input directory on the command line using the '-id' option (which is described above). .PP .SH OUTPUT ERROR LOG .PP All errors and warnings from this program will be logged in the file 'errors.log'. .SH COPYRIGHTS This software is Copyright (c) 1988-1996 Okino Computer Graphics, Inc. All Rights Reserved. .SH TRADEMARKS .PP PolyTrans is a trademark of Okino Computer Graphics, Inc. NuGraf is a registered trademark of Okino Computer Graphics, Inc. .PP Rather than put a trademark symbol in every occurrence of other trademarked names, we state that we are using the names only in an editorial fashion, and to the benefit of the trademark owner, with no intention of infringement of the trademark.